Node / ReticulumProjects / Reticulum.git / files / docs / markdown / using.md

Displaying Rendered • View raw • Download

Reticulum is not installed as a driver or kernel module, as one might expect

of a networking stack. Instead, Reticulum is distributed as a Python module,

containing the networking core, and a set of utility and daemon programs.

This means that no special privileges are required to install or use it. It

is also very light-weight, and easy to transfer to, and install on new systems.

When you have Reticulum installed, any program or application that uses Reticulum

will automatically load and initialise Reticulum when it starts, if it is not

already running.

In many cases, this approach is sufficient. When any program needs to use

Reticulum, it is loaded, initialised, interfaces are brought up, and the

program can now communicate over any Reticulum networks available. If another

program starts up and also wants access to the same Reticulum network, the already

running instance is simply shared. This works for any number of programs running

concurrently, and is very easy to use, but depending on your use case, there

are other options.

Reticulum stores all information that it needs to function in a single file-system

directory. When Reticulum is started, it will look for a valid configuration

directory in the following places:

• T383838/etc/reticulum

• T383838~/.config/reticulum

• T383838~/.reticulum

If no existing configuration directory is found, the directory T383838~/.reticulum

is created, and the default configuration will be automatically created here.

You can move it to one of the other locations if you wish.

It is also possible to use completely arbitrary configuration directories by

specifying the relevant command-line parameters when running Reticulum-based

programs. You can also run multiple separate Reticulum instances on the same

physical system, either in isolation from each other, or connected together.

In most cases, a single physical system will only need to run one Reticulum

instance. This can either be launched at boot, as a system service, or simply

be brought up when a program needs it. In either case, any number of programs

running on the same system will automatically share the same Reticulum instance,

if the configuration allows for it, which it does by default.

The entire configuration of Reticulum is found in the T383838~/.reticulum/config

file. When Reticulum is first started on a new system, a basic, but fully functional

configuration file is created. The default configuration looks like this:

T282828

T8b949e# You should probably edit it to include any additional,

T8b949e# interfaces and settings you might need.

T8b949e# Only the most basic options are included in this default

T8b949e# configuration. To see a more verbose, and much longer,

T8b949e# configuration example, you can run the command:

T8b949e# rnsd --exampleconfig

Tff7b72[reticulum]

T8b949e# If you enable Transport, your system will route traffic

T8b949e# for other peers, pass announces and serve path requests.

T8b949e# This should be done for systems that are suited to act

T8b949e# as transport nodes, ie. if they are stationary and

T8b949e# always-on. This directive is optional and can be removed

T8b949e# for brevity.

Te6edf3enable_transport Tff7b72= Ta5d6ffNo

T8b949e# By default, the first program to launch the Reticulum

T8b949e# Network Stack will create a shared instance, that other

T8b949e# programs can communicate with. Only the shared instance

T8b949e# opens all the configured interfaces directly, and other

T8b949e# local programs communicate with the shared instance over

T8b949e# a local socket. This is completely transparent to the

T8b949e# user, and should generally be turned on. This directive

T8b949e# is optional and can be removed for brevity.

Te6edf3share_instance Tff7b72= Ta5d6ffYes

T8b949e# If you want to run multiple *different* shared instances

T8b949e# on the same system, you will need to specify different

T8b949e# instance names for each. On platforms supporting domain

T8b949e# sockets, this can be done with the instance_name option:

Te6edf3instance_name Tff7b72= Ta5d6ffdefault

T8b949e# Some platforms don't support domain sockets, and if that

T8b949e# is the case, you can isolate different instances by

T8b949e# specifying a unique set of ports for each:

T8b949e# shared_instance_port = 37428

T8b949e# instance_control_port = 37429

T8b949e# If you want to explicitly use TCP for shared instance

T8b949e# communication, instead of domain sockets, this is also

T8b949e# possible, by using the following option:

T8b949e# shared_instance_type = tcp

T8b949e# On systems where running instances may not have access

T8b949e# to the same shared Reticulum configuration directory,

T8b949e# it is still possible to allow full interactivity for

T8b949e# running instances, by manually specifying a shared RPC

T8b949e# key. In almost all cases, this option is not needed, but

T8b949e# it can be useful on operating systems such as Android.

T8b949e# The key must be specified as bytes in hexadecimal.

T8b949e# rpc_key = e5c032d3ec4e64a6aca9927ba8ab73336780f6d71790

T8b949e# It is possible to allow remote management of Reticulum

T8b949e# systems using the various built-in utilities, such as

T8b949e# rnstatus and rnpath. You will need to specify one or

T8b949e# more Reticulum Identity hashes for authenticating the

T8b949e# queries from client programs. For this purpose, you can

T8b949e# use existing identity files, or generate new ones with

T8b949e# the rnid utility.

T8b949e# enable_remote_management = yes

T8b949e# remote_management_allowed = 9fb6d773498fb3feda407ed8ef2c3229, 2d882c5586e548d79b5af27bca1776dc

T8b949e# You can configure Reticulum to panic and forcibly close

T8b949e# if an unrecoverable interface error occurs, such as the

T8b949e# hardware device for an interface disappearing. This is

T8b949e# an optional directive, and can be left out for brevity.

T8b949e# This behaviour is disabled by default.

T8b949e# panic_on_interface_error = No

T8b949e# When Transport is enabled, it is possible to allow the

T8b949e# Transport Instance to respond to probe requests from

T8b949e# the rnprobe utility. This can be a useful tool to test

T8b949e# connectivity. When this option is enabled, the probe

T8b949e# destination will be generated from the Identity of the

T8b949e# Transport Instance, and printed to the log at startup.

T8b949e# Optional, and disabled by default.

T8b949e# respond_to_probes = No

Tff7b72[logging]

T8b949e# Valid log levels are 0 through 7:

T8b949e# 0: Log only critical information

T8b949e# 1: Log errors and lower log levels

T8b949e# 2: Log warnings and lower log levels

T8b949e# 3: Log notices and lower log levels

T8b949e# 4: Log info and lower (this is the default)

T8b949e# 5: Verbose logging

T8b949e# 6: Debug logging

T8b949e# 7: Extreme logging

Te6edf3loglevel Tff7b72= Ta5d6ff4

T8b949e# The interfaces section defines the physical and virtual

T8b949e# interfaces Reticulum will use to communicate on. This

T8b949e# section will contain examples for a variety of interface

T8b949e# types. You can modify these or use them as a basis for

T8b949e# your own config, or simply remove the unused ones.

Tff7b72[interfaces]

T8b949e# This interface enables communication with other

T8b949e# link-local Reticulum nodes over UDP. It does not

T8b949e# need any functional IP infrastructure like routers

T8b949e# or DHCP servers, but will require that at least link-

T8b949e# local IPv6 is enabled in your operating system, which

T8b949e# should be enabled by default in almost any OS. See

T8b949e# the Reticulum Manual for more configuration options.

Tff7b72[[Default Interface]]

Te6edf3type Tff7b72= Ta5d6ffAutoInterface

Te6edf3interface_enabled Tff7b72= Ta5d6ffTrue

If Reticulum infrastructure already exists locally, you probably don’t need to

change anything, and you may already be connected to a wider network. If not,

you will probably need to add relevant interfaces to the configuration, in

order to communicate with other systems.

You can generate a much more verbose configuration example by running the command:

T383838rnsd --exampleconfig

The output includes examples for most interface types supported

by Reticulum, along with additional options and configuration parameters.

It is a good idea to read the comments and explanations in the above default config.

It will teach you the basic concepts you need to understand to configure your network.

Once you have done that, take a look at the Interfaces chapter

of this manual.

Reticulum includes a range of useful utilities, both for managing your Reticulum

networks, and for carrying out common tasks over Reticulum networks, such as

transferring files to remote systems, and executing commands and programs remotely.

If you often use Reticulum from several different programs, or simply want

Reticulum to stay available all the time, for example if you are hosting

a transport node, you might want to run Reticulum as a separate service that

other programs, applications and services can utilise.

It is very easy to run Reticulum as a service. Simply run the included T383838rnsd command.

When T383838rnsd is running, it will keep all configured interfaces open, handle transport if

it is enabled, and allow any other programs to immediately utilise the

Reticulum network it is configured for.

You can even run multiple instances of T383838rnsd with different configurations on

the same system.

Run T383838rnsd:

T282828

Run T383838rnsd in service mode, ensuring all logging output is sent directly to file:

T282828

Generate a verbose and detailed configuration example, with explanations of all the

various configuration options, and interface configuration examples:

T282828

T282828

You can easily add T383838rnsd as an always-on service by configuring a service.

Using the T383838rnstatus utility, you can view the status of configured Reticulum

interfaces, similar to the T383838ifconfig program.

Run T383838rnstatus:

T282828

Filter output to only show some interfaces:

T282828

T282828

When using T383838-R to query a remote transport instance, you must also specify T383838-i with the path to a management identity file that is authorized for remote management on the target system.

With the T383838rnid utility, you can generate, manage and view Reticulum Identities.

The program can also calculate Destination hashes, and perform encryption and

decryption of files.

Using T383838rnid, it is possible to asymmetrically encrypt files and information for

any Reticulum destination hash, and also to create and verify cryptographic signatures.

Generate a new Identity:

T282828

Display Identity key information:

T282828

Encrypt a file for an LXMF user:

T282828

If the Identity for the destination is not already known, you can fetch it from the network by using the T383838-R command-line option:

T282828

Decrypt a file using the Reticulum Identity it was encrypted for:

T282828

T282828

With the T383838rnpath utility, you can look up and view paths for

destinations on the Reticulum network.

Resolve path to a destination:

T282828

T282828

The T383838rnprobe utility lets you probe a destination for connectivity, similar

to the T383838ping program. Please note that probes will only be answered if the

specified destination is configured to send proofs for received packets. Many

destinations will not have this option enabled, so most destinations will not

be probable.

You can enable a probe-reply destination on Reticulum Transport Instances by

setting the T383838respond_to_probes configuration directive. Reticulum will then

print the probe destination to the log on Transport Instance startup.

Probe a destination:

T282828

Send a larger probe:

T282828

If the interface that receives the probe replies supports reporting radio

parameters such as RSSI and SNR, the T383838rnprobe utility will print

these as part of the result as well.

T282828

T282828

The T383838rncp utility is a simple file transfer tool. Using it, you can transfer

files through Reticulum.

Run rncp on the receiving system, specifying which identities are allowed to send files:

T282828

You can also specify allowed identity hashes (one per line) in the file ~/.rncp/allowed_identities

and simply running the program in listener mode:

T282828

From another system, copy a file to the receiving system:

T282828

Or fetch a file from the remote system:

T282828

The default identity file is stored in T383838~/.reticulum/identities/rncp, but you can use

another one, which will be created if it does not already exist

T282828

T282828

The T383838rngit utility provides full Git repository hosting and interaction over Reticulum, as well as many other useful features for software development, collaboration and publishing. It allows you to host Git repositories on Reticulum nodes, interact with remote repositories using standard Git commands through the T383838rns:// URL scheme, and to publish software releases.

The system consists of two parts: The T383838rngit node that hosts and manages repositories, and the T383838git-remote-rns helper that enables Git to communicate with rngit nodes. As soon as you have RNS installed on your system, you can transparently use Git with Reticulum-hosted repositories just like any other type of remote. Git over Reticulum uses URLs in the following format: T383838rns://DESTINATION_HASH/group/repo.

If you set a branch to track a Reticulum remote as the default upstream, you can simply use T383838git as you normally would; all commands work transparently and as expected.

The rngit program is a new addition to RNS! This functionality was introduced in RNS 1.2.0. While great care has been taken to design a secure, but highly configurable and flexible permission system for allowing many users to interact with many different repositories on a single node, T383838rngit has not been tested extensively in the wild! Be careful when hosting repositories, especially if they are public or semi-public.

For the full documentation on the rngit system, see the Git Over Reticulum chapter of this manual.

The T383838rnx utility is a basic remote command execution program. It allows you to

execute commands on remote systems over Reticulum, and to view returned command

output. For a fully interactive remote shell solution, be sure to also take a look

at the rnsh program.

Run rnx on the listening system, specifying which identities are allowed to execute commands:

T282828

From another system, run a command on the remote:

T282828

Or enter the interactive mode pseudo-shell:

T282828

The default identity file is stored in T383838~/.reticulum/identities/rnx, but you can use

another one, which will be created if it does not already exist

T282828

T282828

The T383838rnsh utility provides a fully interactive remote shell over Reticulum.

It allows you to establish encrypted, authenticated shell sessions on remote

systems, complete with terminal emulation, pipe support, and window resizing.

While the T383838rnx utility is useful for simple remote command execution and

retrieving output, T383838rnsh provides a complete interactive terminal experience,

making it ideal for remote administration and management tasks that require

real-time interaction, just like SSH does for IP networks.

T383838rnsh operates in two modes: a listener mode that accepts incoming

connections, and an initiator mode that connects to a remote listener. Both

sides authenticate using Reticulum Identities, ensuring that only authorised

peers can establish sessions.

T383838rnsh provides a genuine interactive terminal over Reticulum. It supports

full terminal emulation including escape sequences, window resizing, signal

forwarding, and piping of standard input, output and error streams. This

makes it suitable for running text editors, terminal multiplexers, and any

other interactive programs on remote systems.

Start T383838rnsh in listener mode, accepting connections from specific identities:

T282828

You can also specify allowed identity hashes (one per line) in the file

T383838~/.rnsh/allowed_identities or T383838~/.config/rnsh/allowed_identities, and

simply run the program in listener mode:

T282828

Connect to a remote listener from another system:

T282828

Specify a command to run on the remote system, separating T383838rnsh options from

the remote command with T383838--:

T282828

Set a default command for the listener, in case the initiator does not supply

one, or when remote command execution is disabled:

T282828

Use the T383838-m flag to mirror the exit code of the remote process:

T282828

Use the T383838-p flag to display the identity and destination hash for a listener:

T282828

Use a specific identity file rather than the default:

T282828

Announce the listener destination on startup, and periodically:

T282828

The T383838-b option specifies the announce period in seconds. Use T3838380 to

announce only once at startup.

By default, T383838rnsh requires that connecting initiators identify themselves

with a Reticulum Identity whose hash is present in the list of allowed

identities. Allowed identities can be specified on the command line with the

T383838-a option, and can be used multiple times:

T282828

You can also maintain a list of allowed identity hashes in the file

T383838~/.rnsh/allowed_identities or T383838~/.config/rnsh/allowed_identities,

with one hex hash per line. This file is reloaded every time a new connection

is received, so changes take effect immediately without restarting T383838rnsh.

If you want to accept connections from any identity (for testing or in fully

trusted environments), you can disable authentication with the T383838-n option:

T282828

Disabling authentication with T383838-n means that any Reticulum peer that

can reach your listener will be able to execute commands on your system. Only

use this option if you really know what you’re doing.

When running in listener mode, T383838rnsh allows you to control how remote

commands are handled:

• By default, the listener accepts the command sent by the initiator. If the

initiator does not supply a command, the listener’s default shell is used.

• Use T383838-C (T383838--no-remote-command) to disable execution of commands received

from the initiator. Only the listener’s default command (or the command

specified after T383838--) will be executed:

T282828

• Use T383838-A (T383838--remote-command-as-args) to append the initiator’s command

to the listener’s default command instead of replacing it. This can be useful

for restricting the remote to a specific program while still allowing the

initiator to pass arguments:

T282828

When running in listener mode, T383838rnsh uses a service name to differentiate

between multiple listener instances that may share the same identity. By

default, the service name is T383838default. You can specify a different service

name with the T383838-s option:

T282828

This allows you to run multiple listeners on the same node, each with a

different service name and purpose.

When connecting to a remote listener, several options are available:

• Use T383838-N (T383838--no-id) to disable sending your identity to the remote

listener. Note that the listener must have authentication disabled (T383838-n)

for the connection to succeed in this case.

• Use T383838-m (T383838--mirror) to make the initiator return with the exit code of

the remote process, rather than always returning T3838380.

• Use T383838-w (T383838--timeout) to specify the connection and request timeout in

seconds. By default, the timeout matches the Reticulum path request timeout.

The default identity file for T383838rnsh is stored at

T383838~/.reticulum/identities/rnsh, but you can specify a different one with the

T383838-i option, which will be created if it does not already exist:

T282828

To display the identity and destination information for a listener, use the

T383838-p option. When combined with T383838-l, both the identity and the listening

destination hash are displayed:

T282828

Like other Reticulum utilities, T383838rnsh supports the T383838-v and T383838-q flags

to increase or decrease logging verbosity. Multiple flags can be specified to

further adjust the log level. The default log level is T383838INFO for listeners

and T383838ERROR for initiators.

T282828

By default, all log output is routed to T383838~/.rnsh/logfile for initiators.

During an active T383838rnsh session, the following escape sequences are

available. These are only recognised immediately after a newline character:

• T383838~~ - Send a literal tilde character

• T383838~. - Terminate the session and exit immediately

• T383838~L - Toggle line-interactive mode

• T383838~? - Display the escape sequence quick reference

T282828

The T383838rnodeconf utility allows you to inspect and configure existing RNodes, and

to create and provision new RNodes from any supported hardware devices.

T282828

For more information on how to create your own RNodes, please read the Creating RNodes

section of this manual.

Reticulum includes built-in functionality for discovering connectable interfaces over Reticulum itself. This is particularly useful in situations where you want to do one or more of the following:

• Discover connectable entrypoints available on the Internet

• Find connectable radio access points in the physical world

• Maintain connectivity to RNS instances with unknown or changing IP addresses

Discovered interfaces can be auto-connected by Reticulum, which makes it possible to create setups where an arbitrary interface can act simply as a bootstrap connection, that can be torn down again once more suitable interfaces have been discovered and connected.

The interface discovery mechanism uses announces sent over Reticulum itself, and supports both publicly readable interfaces and private, encrypted discovery, that can only be decoded by specified network identities. It is also possible to specify which network identities should be considered valid sources for discovered interfaces, so that interfaces published by unknown entities are ignored.

A network identity is a normal Reticulum identity keyset that can be used by

one or more transport nodes to identify them as belonging to the same overall

network. In the context of interface discovery, this makes it easy to manage

connecting to only the particular networks you care about, even if those networks

utilize many individual physical transport node.

This also makes it convenient to auto-connect discovered interfaces only for networks you have some level of trust in.

For information on how to make your interfaces discoverable, see the Discoverable Interfaces chapter of this manual. The current section will focus on how to actually discover and connect to interfaces available on the network.

In its most basic form, enabling interface discovery is as simple as setting T383838discover_interfaces to T383838true in your Reticulum config:

T282828

Once this option is enabled, your RNS instance will start listening for interface discovery announces, and store them for later use or inspection. You can list discovered interfaces with the T383838rnstatus utility:

T282828

You can view more detailed information about discovered interfaces, including configuration snippets for pasting directly into your T383838[interfaces] config, by using the T383838rnstatus -D option:

T282828

In addition to providing local interface discovery information and control, the T383838rnstatus utility can export discovered interface data in machine-readable JSON format using the T383838rnstatus -d --json option. This can be useful for exporting the data to external applications such as status pages, access point maps and similar.

To control what sources are considered valid for discovered sources, additional

configuration options can be specified for the interface discovery system.

• The T383838interface_discovery_sources option is a list of the network or transport identities from which interfaces will be accepted. If this option is set, all others will be ignored. If this option is not set, discovered interfaces will be accepted from any source, but are still subject to stamp value requirements.

• The T383838required_discovery_value options specifies the minimum stamp value required for the interface announce to be considered valid. To make it computationally difficult to spam the network with a large number of defunct or malicious interfaces, each announced interface requires a valid cryptographical stamp, of configurable difficulty value.

• The T383838autoconnect_discovered_interfaces value defaults to T3838380, and specifies the maximum number of discovered interfaces that should be auto-connected at any given time. If set to a number greater than T3838380, Reticulum automatically manages discovered interface connections, and will bring discovered interfaces up and down based on availability. You can at any time add discovered interfaces to your configuration manually, to persistently keep them available.

• The T383838network_identity option specifies the network identity for this RNS instance. This identity is used both to sign (and potentially encrypt) outgoing interface discovery announces, and to decrypt incoming discovery information.

The configuration snippet below contains an example of setting these additional configuration options:

T282828

For more fine-grained control over how discovered interfaces are auto-connected, additional options are provided for configuraiton. These are not necessary to set in most cases, but can be useful in certain situations.

• The T383838autoconnect_interface_mode options specifies which mode discovered interfaces should be created with when auto-connecting.

• The T383838autoconnect_announces_to_internal option allows you to specify that auto-connected interfaces should propagate announces to T383838internal mode interfaces, even if the auto-connected interface’s mode would normally not allow for this.

It is possible to allow remote management of Reticulum

systems using the various built-in utilities, such as

T383838rnstatus and T383838rnpath. To do so, you will need to set

the T383838enable_remote_management directive in the T383838[reticulum]

section of the configuration file. You will also need to specify

one or more Reticulum Identity hashes for authenticating the

queries from client programs. For this purpose, you can use

existing identity files, or generate new ones with the rnid utility.

The following is a truncated example of enabling remote management

in the Reticulum configuration file:

T282828

For a complete example configuration, you can run T383838rnsd --exampleconfig.

Reticulum networks are fundamentally permissionless and open, allowing anyone with a compatible interface to participate. While this openness is essential for a resilient and decentralized network, it also exposes the network to potential abuse, such as peers flooding the network with excessive announce broadcasts or other forms of resource exhaustion.

The Blackhole system provides tools to help manage this problem. It allows operators and individual users to block specific identities at the Transport layer, preventing them from propagating announces through your node, and for other nodes to reach them through your network.

There is fundamentally no way to globally block or censor any identity or destination in Reticulum networks. The blackhole functionality will prevent announces from (and traffic to) all destinations associated with the blackholed identity on your own network segments only.

This provides users and operators with control over what they want to allow on their own network segments, but there is no way to globally censor or remove an identity, as long as someone is willing to provide transport for it.

This functionality serves a dual purpose:

• For Individual Users: It offers a simple way to maintain a quiet and efficient local network by manually blocking spammy or unwanted peers.

• For Network Operators: It enables the creation of federated, community-wide security standards. By publishing and sharing blackhole lists, operators can protect large infrastructures and distribute spam filtering rules across the mesh without manual intervention.

The most immediate way to manage unwanted identities is through manual configuration using the T383838rnpath utility. This allows you to instantly block or unblock specific identities on your local Transport Instance.

To block an identity, use the T383838-B (or T383838--blackhole) flag followed by the identity hash. You can optionally specify a duration and a reason, which are useful for logging and future reference.

T282828

You can also add a duration (in hours) and a reason:

T282828

To remove an identity from the blackhole, use the T383838-U (or T383838--unblackhole) flag:

T282828

To see all identities currently blackholed on your local instance, use the T383838-b (or T383838--blackholed) flag:

T282828

Manually blocking identities is effective for immediate threats and annoyances, but maintaining an up-to-date blocklist across many nodes on a large network is impractical. Reticulum supports automated list sourcing, allowing your node to subscribe to blackhole lists maintained by trusted peers, or a central authority you manage yourself.

Verify Before Subscribing! Subscribing to a blackhole source is a powerful action that grants that source the ability to dictate who you can communicate with. Before adding a source to your configuration, verify that the maintainer aligns with your usage policy and values. Blindly subscribing to untrusted lists could inadvertently block legitimate peers or essential services.

When enabled, your Transport Instance will periodically (approximately once per hour) connect to configured sources, retrieve their latest blackhole lists, and automatically merge them into your local blocklist. This provides “set-and-forget” protection for both individual users and large networks.

To enable automated sourcing, add the T383838blackhole_sources option to the T383838[reticulum] section of your configuration file. This option accepts a comma-separated list of Transport Identity hashes that you trust to provide valid blackhole lists.

T282828

Te6edf3...

T8b949e# Automatically fetch blackhole lists from these trusted sources

Te6edf3blackhole_sources Tff7b72= Ta5d6ff521c87a83afb8f29e4455e77930b973b, 68a4aa91ac350c4087564e8a69f84e86

T8b949e# Optional update interval, defaults to one hour

Te6edf3blackhole_update_interval Tff7b72= Ta5d6ff60

Te6edf3...

1. When enabled, the T383838BlackholeUpdater service runs in the background.

2. For every identity hash listed in T383838blackhole_sources, it attempts to establish a temporary link to its associated\T383838\rnstransport.info.blackhole\T383838\ destination.

3. It requests the T383838/list path, which returns a dictionary of blackholed identities and their associated metadata.

4. The received list is merged with your local T383838blackholed_identities database.

5. The lists are persisted to disk, ensuring they survive restarts.

You can verify the external lists you are subscribed to, and their contents, without importing them by using T383838rnpath -p. See the rnpath utility documentation for details on querying remote blackhole lists.

If you are operating a public gateway, a community hub, or simply wish to share your blackhole list with others, you can configure your instance to act as a blackhole list publisher. This allows other nodes to subscribe to your definitions of unwanted traffic.

To publish your local blackhole list, enable the T383838publish_blackhole option in the T383838[reticulum] section:

T282828

Te6edf3...

Te6edf3publish_blackhole Tff7b72= Ta5d6ffyes

Te6edf3...

When this is enabled, your Transport Instance will register a request handler at T383838rnstransport.info.blackhole. Any peer that connects to this destination and requests T383838/list will receive the complete set of identities currently present in your local blackhole database.

The blackhole system relies on the trust relationship between the subscriber and the publisher. By subscribing to a source, you are implicitly trusting that source to only block identities that are genuinely detrimental to the network.

As the ecosystem matures, this system is designed to integrate with Network Identities. This allows communities to verify that a published blackhole list is actually provided by a specific network or organization with a certain level of reputation and trustworthiness, adding a layer of cryptographic trust to the federation process. This prevents malicious actors from publishing fake lists intended to censor legitimate traffic.

For operators, this creates a scalable model where maintaining a single high-quality blocklist can protect thousands of downstream peers, drastically reducing the administrative.

If you are setting up a system for permanent use with Reticulum, there is a

few system configuration changes that can make this easier to administrate.

These changes will be detailed here.

On a Reticulum instance with several serial port based interfaces, it can be

beneficial to use the fixed device names for the serial ports, instead

of the dynamically allocated shorthands such as T383838/dev/ttyUSB0. Under most

Debian-based distributions, including Ubuntu and Raspberry Pi OS, these nodes

can be found under T383838/dev/serial/by-id.

You can use such a device path directly in place of the numbered shorthands.

Here is an example of a packet radio TNC configured as such:

T282828

Using this methodology avoids potential naming mix-ups where physical devices

might be plugged and unplugged in different orders, or when device name

assignment varies from one boot to another.

Instead of starting Reticulum manually, you can install T383838rnsd as a system

service and have it start automatically at boot.

If you installed Reticulum with T383838pip, the T383838rnsd program will most likely

be located in a user-local installation path only, which means T383838systemd will not

be able to execute it. In this case, you can simply symlink the T383838rnsd program

into a directory that is in systemd’s path:

T282828

You can then create the service file T383838/etc/systemd/system/rnsd.service with the

following content:

T282828

Be sure to replace T383838USERNAMEHERE with the user you want to run T383838rnsd as.

To manually start T383838rnsd run:

T282828

If you want to automatically start T383838rnsd at boot, run:

T282828

Alternatively you can use a user systemd service instead of a system wide one. This way the whole setup can be done as a regular user.

Create a user systemd service files T383838~/.config/systemd/user/rnsd.service with the following content:

T282828

Replace T383838RNS_BIN_DIR with the path to your Reticulum binary directory (eg. /home/USERNAMEHERE/rns/bin).

Start user service:

T282828

If you want to automatically start T383838rnsd without having to log in as the USERNAMEHERE, do:

T282828